Comment API Design Decisions

Learn some intricacies in the design of our proposed API for the comment service.

The API design for a service not only depends on the organization's requirements and the services they provide, but it also depends on the internal details of the system's overall architecture. These decisions further pave the way to adopt a specific API architecture style to direct the communication between the clients and back-end services. In the following section, we'll discuss the detailed working of the comment system and the interaction between various components, which enable us to make some design decisions before embarking on the design problem.

Design overview#

The following figure demonstrates how a comment system works. All client requests are passed through the API gateway and fan out to multiple back-end services. Upon receiving a comment for a post, the back-end server sets various attributes for the comment, appends it to the relevant post, and stores it in the database. Other requests, such as updating or deleting a comment, are handled similarly.

How a comment service works
How a comment service works

For brevity, we assume that our comment service offers only textual content as part of the comment. The following table describes some of the essential components involved in the design of the comment service.

Components and Services Details

Component or Service

Details

User service

  • Stores user-relevant data
  • Makes use of a cache and a relational database

Comment service

  • Stores the comments in the relevant database
  • Communicates with the other services
  • Caches the top N (say, top 10) comments


Posts service

  • Handles the content and metadata related to posts
  • Cache stores frequently visited posts
  • Blob storage keeps media files including images and videos

Persistent layer

  • Stores the comments, posts, and the relevant media files

API gateway

  • Authenticates and authorizes a user request
  • Performs request throttling and caching of frequent API calls

Workflow#

Let's go over how all the components involved in the comment service interact with each other to perform an operation requested by a client.

The client-initiated requests are passed through the API gateway. The API gateway performs operations relevant to identity and access management—whether to allow the request for further processing or not. Upon successful verification, the user can perform more operations, such as creating, retrieving, editing, or deleting a comment.

The API gateway directs the requests to the comment service. Whenever a request for a comment is received, this service further consults with the other services, the user and the posts service, to fetch the required information relevant to a comment. For example, when a user wants to create a comment, the comment service validates the user information via user service. Similarly, the post on which the comment is made is determined via the posts service. Furthermore, the comment is created and stored with the relevant user and post information and other metadata via the comment service.

Point to Ponder

Question

What changes in the comment system design can be proposed if we allow users to add media files, such as images and videos, to their comments?

Hide Answer

Since we would need to store the media files at the backend, we’d need to add blob storage, along with a comments cache and comments database.

Here, the point of interest is which architectural style we need to use for communication between the three main components: the client, API gateway, and back-end services. What are the criteria for adopting a specific architectural style? We’ll answer this question in the following section.

Design considerations#

We have seen how the comment system works. We can now decide on an API architecture style for the interaction between the client, the API gateway, and the back-end services. Let’s go over the data formats and HTTP version to be adopted in the design of our API.

Architecture styles#

First, we’ll describe the interaction between the client, API gateway, and comment service with respect to different API architecture styles.

Client to API gateway#

The primary tasks relevant to comments are creating, retrieving, updating, and deleting comments. All these tasks can be performed via CRUD operations that best fit the REST API architecture style. So here, we adopt the REST style without embedding any additional complexities amid the interacting entities.

API architecture style for the interaction between the client and API gateway
API architecture style for the interaction between the client and API gateway

API gateway to back-end services#

An interesting part of the design is deciding the architecture style for the interaction between the API gateway and back-end servers. Let's evaluate the suitability of architectural styles for the interaction between these two entities.

  • REST: This style provides a standardized way to manage and access structured resources—in our case, the user comments. Furthermore, REST provides CRUD operations and is relatively simpler than GraphQL, making it a suitable option for our service.

  • GraphQL: In the comment system, we have three data sources that could be accessed by multiple client applications—for example, mobile and web applications. GraphQL is a better option for an application where a single data source is shared by multiple clients or if data is to be retrieved from multiple endpoints. Another disadvantage of GraphQL is that it is overly complicated to implement, which means we should avoid using it for a simple service like the comment API. Furthermore, the efficiency that GraphQL may offer would be negligible compared to the complexities it would introduce in a simple service like that of comments.

  • gRPC: This architecture style is action oriented and is used when we aim to trigger a function or procedure in the back-end system. Also, gRPC is a suitable choice when there is intensive communication between entities and a persistent connection is required. However, in the comment service, we aim to manipulate resources that can be performed via CRUD operations, which are more aligned with the REST architecture style.

API architecture style for the interaction between the API gateway and back-end servers
API architecture style for the interaction between the API gateway and back-end servers

By comparing and considering different architecture styles, we conclude that REST is the most suitable API architecture style to adopt for communication between the API gateway and back-end servers. However, we should note that each style has its own pros and cons. There aren’t any strict use cases or rules about adopting one instead of the other. However, to enhance the effectiveness of communication between any two systems, we need to opt for the style that has the most advantages over the others.

Quiz

Q

In our design, the comment service should communicate with the other two services—posts, and user service, to fetch the relevant data. In light of this, which architectural style should we adopt for communication between these services?

Your Answer
A)

gRPC

Explanation

gRPC is the best option, which is recommended for server-to-server communication.

B)

REST

C)

GraphQL

D)

None of the above

Data formats#

Several data formats exist that can be adopted in our proposed API for a comment server, as given below:

  • JSON: We need to exchange data related to comments between a client and a server—for example, comment IDs to be retrieved, thread IDs, and comment text. JSON suits our requirements because it is human readable and more compact than the XML and HTML data formats.

  • XML: Although XML can represent more complicated data than JSON and supports object representations as well, it has several significant disadvantages that make it less ideal for our API service, including greater encoded file sizes and a lack of built-in support for parsers.

  • Binary: When compared to textual representations, binary formats are quick to process and less in size, but they compromise human readability, making it difficult to troubleshoot issues and comprehend errors. This format is suitable in cases when we need to transfer large files, such as images, videos, and so on. However, for sending a number of entities and retrieving comments, adopting the binary data formats could be an expensive choice.

JSON is the suitable choice for client and API gateway communication for better readability and debugging. In fact, it’s also a good choice for communication between the API gateway and back-end services because the comment service also uses REST architecture for downstream services. Furthermore, the data exchanged using the comments service is limited. Therefore, using binary formats will offer little efficiency in comparison to the complexity it will add.

Quiz

Question

Why can’t we use the binary format instead of JSON to exchange data between the client and server?

Hide Answer

The binary format is a suitable option because it is less in size, and the compression algorithms are well suited for such data. However, the overhead of encoding ASCII (or any other code) into binary and back to ASCII prevents us from adopting the binary format for the comment API.

HTTP version#

We have HTTP/1.1, HTTP/2.0, and HTTP/3.0 in hand. Let's see which protocol to choose for our API.

  • HTTP/1.1: The comment operations are simple CRUD, and we need a reliable connection to perform such operations; therefore, HTTP/1.1 is a suitable choice. This version is suitable when we don't want to provide a live comments service where comments are queued and batch processed frequently.

  • HTTP/2.0: The main features of HTTP/2.0 are backward compatibility, multiplexing, and headers compression. HTTP/2.0 is optimal when there is an enormous number of concurrent client requests on a platform where users can post comments on live content. HTTP/2.0 could be an optimal choice because it supports multiplexing and headers compression, thereby reducing latency and bandwidth needs. However, we opted for JSON instead of binary for exchanging data between client and server; therefore, choosing HTTP/2.0 may not be an optimal choice in the comment API.

  • HTTP/3.0: Since this HTTP version is faster than the previous versions, adopting this version in the API would make the system more efficient. However, this version is still in its infant version, and most organizations are still transitioning from HTTP/1.1 to HTTP/2.0. Therefore, Clients and servers should support this version to avoid incompatibility in the future, which might be a bit early in today's era.

Summary#

In this lesson, we focused on various design considerations that affect the design of our API for a comment service. We discussed various architecture styles, data formats, HTTP versions, and security mechanisms to adopt while designing the API. The following table summarizes the design decisions that have been taken and will be followed in the next lesson to devise message formats relevant to various operations on comments.

Design Considerations

Client to API Gateway

API Gateway to Backend

Architecture style

REST

REST

Data format

JSON

JSON

HTTP version

HTTP/1.1

HTTP/1.1

Requirements of the Comment API

API Model for Comment Service